Function: on(domElementOrNodeArrayOrCSSSelector, stringEventNameOrKeyValueMap, functionCallback(event, DC, savedParams), paramsToSave, stringNamespace )

Description: Sets one or more event handlers to exicute when triggered.

Returns: domElement or matching node array, or $A object if chained.

Note: The event naming syntax also supports event namespacing, so that multiple events can be added using the same namespace for grouped events, or the stringNamespace parameter may be used for this purpose instead when applying multiple event handlers.

Example:

// Bind an event handler to a DOM element.
var myElement = $A.on(domElement, "click", function(event, DC) {
  // DC will automatically populate If a DC object is bound to the referenced element as its triggering element.
});

// Bind multiple events to a handler on DOM elements referenced with a CSS selector and store additional data
var myElementsArray = $A.on("a.tooltip-trigger", "focus mouseover", function(event, DC, data) {
  // data is populated by whatever is passed in the third parameter of on()
  // In this case, data = "Testing"
}, "Testing");

// Bind multiple event handlers to a DOM element.
var myElement = $A.on(domElement, {
  focus: function(event, DC) {
    // Do something
  },
  blur: function(event, DC) {
    // Do something
  },
  mouseenter: function(event, DC) {
    // Do something
  }
});

// Bind a namespaced event handler to a DOM element.
var myElement = $A.on(domElement, "click.myNamespace", function(event, DC) {
  // Do something
});

// Bind multiple namespaced events to a handler on DOM elements referenced with a CSS selector and store additional data
var myElementsArray = $A.on("a.tooltip-trigger", "focus.myNamespace mouseover.myNamespace", function(event, DC, data) {
  // Here, data = "Testing"
}, "Testing");

// Bind multiple events to a handler on DOM elements referenced with a CSS selector, store no additional data, and namespace all events using the stringNamespace parameter.
var myElementsArray = $A.on("a.tooltip-trigger", "focus mouseover", function(event, DC, data) {
    // Do something
}, ".myNamespace");

// Bind multiple namespaced event handlers to a DOM element and store additional data.
var myElement = $A.on(domElement, {
  "focus.myNamespace": function(event, DC, data) {
    // Do something
  },
  "blur.myNamespace": function(event, DC, data) {
    // Do something
  },
  "mouseenter.myNamespace": function(event, DC, data) {
    // Do something
  }
},
// Stored data (may be any object type except a function)
"Stored data");

// Bind multiple namespaced event handlers to a DOM element using the stringNamespace parameter.
var myElement = $A.on(domElement, {
  focus: function(event, DC, data) {
    // Do something
  },
  blur: function(event, DC, data) {
    // Do something
  },
  mouseenter: function(event, DC, data) {
    // Do something
  }
}, ".myNamespace");

// Or the same using chaining

// Bind an event handler to a DOM element.
var myChain = $A(domElement).on("click", function(event, DC) {
  // DC will automatically populate If a DC object is bound to the referenced element as its triggering element.
});

// Bind multiple events to a handler on DOM elements referenced with a CSS selector and store additional data
var myChain = $A("a.tooltip-trigger").on("focus mouseover", function(event, DC, data) {
  // data is populated by whatever is passed in the third parameter of on()
  // In this case, data = "Testing"
}, "Testing");

// Bind multiple event handlers to a DOM element.
var myChain = $A(domElement).on({
  focus: function(event, DC) {
    // Do something
  },
  blur: function(event, DC) {
    // Do something
  },
  mouseenter: function(event, DC) {
    // Do something
  }
});

// Bind a namespaced event handler to a DOM element.
var myChain = $A(domElement).on("click.myNamespace", function(event, DC) {
  // Do something
});

// Bind multiple namespaced events to a handler on DOM elements referenced with a CSS selector and store additional data
var myChain = $A("a.tooltip-trigger").on("focus.myNamespace mouseover.myNamespace", function(event, DC, data) {
  // Here, data = "Testing"
}, "Testing");

// Bind multiple namespaced event handlers to a DOM element and store additional data.
var myChain = $A(domElement).on({
  "focus.myNamespace": function(event, DC, data) {
    // Do something
  },
  "blur.myNamespace": function(event, DC, data) {
    // Do something
  },
  "mouseenter.myNamespace": function(event, DC, data) {
    // Do something
  }
},
// Stored data (may be any object type except a function)
"Stored data");

// To return the modified element within a chain, use the "return()" method.

var myElement = myChain.return();